I think from a DX point of view, the new one is worse. I believe they should be documented together for ease.

I agree with @ndossche here. If the tooling is struggling then it's a tooling issue. I am happy to modify the markup if it brings more consistency (e.g. replacing the table with a <variableentrylist>) or improves the DX while also facilitating tooling.

Converting the table to use the more typical format of a <variableentrylist> with multiple <term> tags that can hold the XML ID seems a better approach than duplicating rows.

I think the table format is correct here, as it includes the value, while the list format usually doesn't as far as I know.

There's a precedent for a similar situation at https://www.php.net/manual/en/reserved.constants.php: ZEND_THREAD_SAFE and PHP_ZTS. Here, the manual also duplicates them, but notes that PHP_ZTS is an alias of ZEND_THREAD_SAFE.

So in my opinion, a similar approach could work fine in case of ext/dom constants: we could mark them as aliases, and document them in the same row. What do you think?

Although, I should mention that personally, I don't find the separe row based approach worse, the page even looks cleaner for me because it's easier to overview the constant names. I attach two screenshots for comparison.

original:

new:

We decided that providing the value of a constant is not useful as this is not something people should actually care about. Especially as it could change at any moment by an underlying library. So this is a feature of the list based constant design.

Most constant lists are varentrylists and not tables.

I also don't want to mention that one of the "legacy" or "new" constants is an alias of another one, and I don't want to duplicate text, as that just gives more work for translators. So having both constants together is the better solution.

I also don't want to mention that one of the "legacy" or "new" constants is an alias of another one, and I don't want to duplicate text, as that just gives more work for translators. So having both constants together is the better solution.

I would make the two constants aliases in the stub file, and document them in the same row. But then what should be written in the name column that works for all DOM constants and for the rest of the aliased constants (ZEND_THREAD_SAFE and PHP_ZTS)?